home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / Tools / ObjectTcl-1.1 / docs / BindingRef.txt < prev    next >
Encoding:
INI File  |  1995-06-30  |  9.8 KB  |  263 lines
  1. [Image]
  2.     ------------------------------------------------------------------------
  3.  
  4.  
  5. Contents
  6.  
  7.      Introduction
  8.      Restrictions
  9.      CDL Processing
  10.      Class Definition Language (CDL)
  11.           Syntax
  12.           Argument Types
  13.           Return Types
  14.      C++ Objects
  15.      Exceptions
  16.  
  17.     ------------------------------------------------------------------------
  18.  
  19.  
  20. Introduction
  21.  
  22. The Object Tcl extension is implemented in C++ in such a way as to promote the
  23. use and reuse of C++ classes from within Object Tcl scripts.
  24.  
  25. Object Tcl makes it possible to:
  26.  
  27.      Create, manipulate and destruct C++ classes from within the Object Tcl
  28.      domain.
  29.      Create, manipulate and destruct Object Tcl classes, that inherit from C++
  30.      classes, from within the C++ domain.
  31.      Inherit Object Tcl classes from built-in C++ classes. Note that the
  32.      dynamic binding of methods crosses the domain from C++ to Object Tcl and
  33.      vice versa.
  34.      Pass Object Tcl objects, of a class that inherits from an existing C++
  35.      class, into the C++ domain for manipulation and possible destruction.
  36.      Re-implement Object Tcl classes in C++ for performance improvements and
  37.      access to the more esoteric OS or third party library facilities with
  38.      minimal effort.
  39.  
  40. Object Tcl provides an interpreted extension to the C++ language while still
  41. maintaining the support for object orientation.
  42.  
  43. This page describes how C++ classes may be exported to the Object Tcl system
  44. for use from Tcl.
  45.     ------------------------------------------------------------------------
  46.  
  47.  
  48. Restrictions
  49.  
  50. There are a few restrictions on the usage of C++ and Object Tcl. These
  51. restrictions are described below:
  52.  
  53.   1. C++ makes it possible to have many methods with the same name that can be
  54.      distinguished by their formal arguments. In C++ this is called
  55.      overloading. Tcl is weakly typed and it is therefore impossible to
  56.      disambiguate the methods based on the types of the formal arguments. For
  57.      this reason method overloading is not supported.
  58.  
  59.      If a C++ class does have more than one method with a given name and it is
  60.      to be exported to Object Tcl then the CDL for this class must describe
  61.      only one of them.
  62.  
  63.      The most common occurrence of overloading is in class constructors. Only
  64.      one constructor for a C++ class may be exported to Object Tcl.
  65.  
  66.   2. C++ provides support for defining the behavior of operations upon a class.
  67.      This is called operator overloading. Object Tcl does not support this.
  68.      Operators on a C++ class cannot be exported into Object Tcl.
  69.  
  70.   3. As Tcl is weakly typed, with all types represented as strings, then there
  71.      are restrictions on the parameters and return types that may be passed
  72.      back and forth between the two domains. The CDL processor is designed in a
  73.      way to make it easy to build in additional type conversion support.
  74.  
  75.     ------------------------------------------------------------------------
  76.  
  77.  
  78. CDL Processing
  79.  
  80. The Object Tcl system includes a CDL processor called "cdl". The CDL processor
  81. takes files in the CDL format and generates C++ files that will bind the
  82. application's C++ classes into Object Tcl.
  83.  
  84. The CDL processor takes three arguments: the first is a flag indicating whether
  85. the CDL processor is to generate a header file (-h) or source file (-s), the
  86. second is the name of the input file, including suffix, and the third is the
  87. output file, including suffix.
  88.  
  89. For each CDL file, the CDL processor must be invoked twice, once to generate
  90. the header file and once to generate the source file.
  91.  
  92. Rules can be added to makefiles to automatically take CDL files, with a
  93. suitable suffix, and generate C++ files that are then compiled into object
  94. files. The source distribution contains examples of makefiles that have such
  95. rules.
  96.  
  97. The C++ code generated by the CDL processor uses C++ static constructors to
  98. facilitate the inclusion of an application's C++ classes into the Object Tcl
  99. environment with absolutely no modification of the application code. Only a
  100. relink is necessary.
  101.     ------------------------------------------------------------------------
  102.  
  103.  
  104. Class Definition Language
  105.  
  106. CDL files contain descriptions of the C++ classes that are to be exported to
  107. Object Tcl.
  108.  
  109. Syntax
  110.  
  111. The CDL processor is based around a Tcl interpreter itself, hence the
  112. familiarity of the CDL syntax.
  113.  
  114. In a CDL file there are two commands:
  115.  
  116. pass -(h|s) arg
  117.  
  118. and
  119.  
  120. class ?-isA classList? name desc
  121.  
  122. The pass command takes the rest of the arguments and passes them straight
  123. through to the generated C++ file. The pass command is generally used to place
  124. #include directives in the generated C++ but it is also useful for placing
  125. comments or version identifiers in the C++ files. The -h or -s flag may be used
  126. to specify that the arg is only passed to the header file or source file
  127. respectively. If the destination flag is omitted then the arg will be passed to
  128. both the header and source files.
  129.  
  130. The class command is used to describe a C++ class to the Object Tcl system. The
  131. name argument is the name of the class. The -isA classList optional parameter
  132. can be used to specify the list of superclasses, both direct and indirect, of
  133. this class. The list of superclasses is used for coercing the types of objects
  134. when they are passed between Tcl and C++ using the obptr and obref CDL types.
  135. The desc argument is a Tcl script that may use the following commands
  136. internally:
  137.  
  138. constructor args
  139.      This command describes the constructor for the C++ class that will be
  140.      exported to Object Tcl. The args argument is a Tcl script that may use the
  141.      argument type commands.
  142.  
  143. method name (-dynamic | -static) args rtn
  144.      This command describes an instance method that will be exported to Object
  145.      Tcl. The name argument is the name of the method; the -dynamic or -static
  146.      switch indicates whether the method is a C++ virtual method or not. The
  147.      args argument is a Tcl script that may use the argument type commands, and
  148.      the rtn argument is a script that may use one of the return type commands.
  149.  
  150.      A C++ virtual method can be exported as -static in which case the dynamic
  151.      binding will stop at the Object Tcl/C++ interface. This may be of use in
  152.      some cases as the use of the -dynamic option causes a performance overhead
  153.      even if the method is not redefined in an Object Tcl subclass.
  154.  
  155. classMethod name args rtn
  156.      This command describes a class method (a C++ static member function) that
  157.      will be exported to Object Tcl. The name argument is the name of the
  158.      method. The args argument is a Tcl script that may use the argument type
  159.      commands, and the rtn argument is a script that may use one of the return
  160.      type commands.
  161.  
  162. Argument Types
  163.  
  164. The arg parameter of the constructor, method and classMethod commands is a Tcl
  165. script that can make use of the following commands:
  166.  
  167.      int
  168.      float
  169.      double
  170.      str
  171.      obptr className
  172.      obref className
  173.  
  174. The className argument to the obptr and obref commands specifies the actual
  175. class expected by the C++ method.
  176.  
  177. The CDL processor is designed to make it easy to support new type conversions
  178. between the C++ and the Object Tcl domains.
  179.  
  180. Return Types
  181.  
  182. The rtn parameter of the method and classMethod commands is a Tcl script that
  183. can make use of the following commands:
  184.  
  185.      int
  186.      float
  187.      double
  188.      str
  189.      obptr className
  190.      obref ?-new? className
  191.  
  192. The className argument to the obptr and obref commands specifies the actual
  193. class returned by the C++ method.
  194.  
  195. The -new flag for the obref return type may be used to indicate that a copy of
  196. the returned object should be made on the heap.
  197.  
  198. As with argument types, the CDL processor is designed to make it easy to add
  199. new type conversions between C++ and the Object Tcl domains.
  200.     ------------------------------------------------------------------------
  201.  
  202.  
  203. C++ Objects
  204.  
  205. Prior to beta 1.1 of Object Tcl, it was not possible to create a C++ object
  206. from within the C++ domain and then pass it into Object Tcl for manipulation.
  207.  
  208. Beta 1.1 of Object Tcl removes this restriction by allowing the C++ domain to
  209. create instances of class_otcl with the constructor described in the CDL
  210. description. For example:
  211.  
  212. return new Shape(300,300);
  213.  
  214. This new Shape object could not be passed back to Object Tcl but now you can
  215. write:
  216.  
  217. return new Shape_otcl(300,300);
  218.  
  219. and pass the new Shape object into Object Tcl.
  220.  
  221. This requires the C++ domain to include header files generated by the CDL
  222. processor.
  223.     ------------------------------------------------------------------------
  224.  
  225.  
  226. Exceptions
  227.  
  228. Dynamic binding of methods makes it possible for a C++ method invocation to
  229. result in the execution of a method described in Tcl. It is quite possible for
  230. the Tcl to be incorrect and generate an exception.
  231.  
  232. It is possible to catch exceptions in three ways.
  233.  
  234. General exception handler
  235.  
  236. By default, any exception in a Tcl method body invoked from the C++ domain will
  237. result in the error being reported to stdout and the application terminating
  238. with an error status.
  239.  
  240. Object exception handler in Tcl
  241.  
  242. It is possible to implement an instance method called otclErrorMethod on an
  243. Object Tcl class. This method will be called on any Tcl exception that occurs
  244. when a method is invoked from C++.
  245.  
  246. The otclErrorMethod takes two parameters. The first parameter is the name of
  247. the method that caused the exception; the second is the error message generated
  248. by the exception.
  249.  
  250. Object exception handler in C++
  251.  
  252. It is possible to implement an instance method called otclErrorMethod on a C++
  253. class in the same manner as for Object Tcl classes described above. This method
  254. must be exported to the Object Tcl system via the CDL description and it must
  255. take two arguments, both of which are of type char *.
  256.     ------------------------------------------------------------------------
  257.  
  258. Object Tcl | Overview | Language Reference | C++ Binding Reference | Example |
  259. Source Code
  260.     ------------------------------------------------------------------------
  261.  
  262. otcl@x.co.uk
  263.